Skip to main content

Query Keys

在其核心，TanStack Query根据查询键来管理查询缓存。查询键必须是一个数组，可以是一个简单的只包含单个字符串的数组，也可以是一个包含多个字符串和嵌套对象的复杂数组。只要查询键是可序列化的，并且对于查询的数据是唯一的，就可以使用它！

简单的查询键 Simple Query keys​

最简单的键形式是一个包含常量值的数组。这种格式适用于：

  • 通用的列表/索引资源
  • 非层次结构资源
// 一个待办事项列表
useQuery({ queryKey: ['todos'], ... })

// 其他任何内容！
useQuery({ queryKey: ['something', 'special'], ... })

带变量的数组键 Array Keys with variables​

当查询需要更多信息来唯一描述其数据时，可以使用一个包含字符串和任意数量的可序列化对象的数组来描述它。这对于：

  • 层次结构或嵌套资源
    • 通常会传递ID、索引或其他基本类型来唯一标识项目
  • 带有附加参数的查询
    • 通常会传递一个包含额外选项的对象
// An individual todo
useQuery({ queryKey: ['todo', 5], ... })

// An individual todo in a "preview" format
useQuery({ queryKey: ['todo', 5, { preview: true }], ...})

// A list of todos that are "done"
useQuery({ queryKey: ['todos', { type: 'done' }], ... })

查询键具有确定性哈希！Query keys are hashed deterministically​

这意味着无论对象中键的顺序如何，以下所有查询都被认为是相等的:

useQuery({ queryKey: ['todos', { status, page }], ... })
useQuery({ queryKey: ['todos', { page, status }], ...})
useQuery({ queryKey: ['todos', { page, status, other: undefined }], ... })

然而，以下查询键是不相等的。数组项的顺序很重要！

useQuery({ queryKey: ['todos', status, page], ... })
useQuery({ queryKey: ['todos', page, status], ...})
useQuery({ queryKey: ['todos', undefined, page, status], ...})

如果您的查询函数依赖于一个变量，请将其包含在查询键中​

由于查询键唯一地描述了它们获取的数据，所以它们应该包含在查询函数中使用的任何会发生变化的变量。例如：

function Todos({ todoId }) {
  const result = useQuery({
    queryKey: ['todos', todoId],
    queryFn: () => fetchTodoById(todoId),
  })
}